TeX 1995 July/TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO/dviware/dvidis/dvidis.doc

Text File | 1990-10-01 | 11KB | 266 lines

        This documentation corresponds to DVIDIS V3.4


DVIDIS is a program that displays TeX DVI files on a VaxStation running VWS.

                  N O T E

    If you have used previous versions of DVIDIS, note that this
    version is VERY different.  The human interface is much better,
    but most important, the program now reads PK format font files,
    note the old, very obsolete RST format font files.  It is possible
    to build a version with RST file support, but that hasn't been
    tested and is not recommended.  PK fonts are MUCH better in every way.

Basic usage is very simple.  To display file TEXT.DVI, for example, just type:
        $ DVIDIS TEXT

on your VAXStation.  A large window will be created, and your text should
start to appear in it; depending on the paper size and where you have located
your window (by default it starts out centered), you may be able to see the
"edge" of the paper as a gray bar.  Meanwhile, your keyboard will remain
attached to the window you were previously in, and you can enter commands.
For a list of commands available to you, hit the HELP key.  The effect of
the various commands is easy to see, so experiment until you feel comfortable
with them.

You can also specify a couple of options on the DVIDIS command line.  These
CANNOT be changed once DVIDIS has started.  All options are of the form "-l"
where "l" is any single letter, with the single exception of -verbose (for
historical reasons).  Some are followed - after a space - by one or a pair of
numeric arguments; the -s command must be followed  by a paper size specifica-
tion.

For example:

        $ DVIDIS -w -p 2 4 TEXT

means "display pages 2 to 4 of TEXT.DVI in 'wide' mode."

The following options are commonly used:

-c    The fonts that DVIDIS uses are meant for a 300 dpi printer.  A VAXSta-
    tion display has about 78 dpi.  As a result, if you display the glyphs
    from these fonts at a 1-1 pixel-to-pixel mapping, they are about 4
    times as large as they would be on the page, and only about 1/9 of the
    page is visible at a time.  Normally, DVIDIS compresses all fonts by a
    2-to-1 factor.  The fonts are still readable, but you can now get most
    of the width of a page - all, with any reasonable margins - and over
    half the height on the screen.  Specifying "-c" turns off this com-
    pression; it's useful mainly for looking at the glyphs, not the text.

-w    Specifies a 4-to-1 glyph compression factor.  This allows you to see
    how a whole page looks, but unfortunately it's rather hard to read
    the resulting text.

-m    Tells DVIDIS to try to use smaller fonts, rather than compressing
    larger ones.  This only works if you actually HAVE the small fonts on
    your system.  When it works, it improves the appearance of individual
    characters, although it often makes lines come out with slightly
    different lengths than they should.  -m is especially useful in
    conjunction with -w.  -m in conjunction with -c is meaningless.

-s ss    Set the paper size.  This determines what size paper the program
    assumes you are printing on.  The default is "letter", which is
    8.5 x 11 inch es.  The argument is the name of a paper size; type
    DVIDIS -s ? for a list of possible values.

    The paper size controls where DVIDIS places a visible gray border,
    and when it tells you that characters have "run off the page".  It
    always displays the characters, however.

    Paper size "huge" is meant for special purposes; using it will make
    many of the commands you can type to DVIDIS while it is running work
    in strange ways.  You should generally avoid using size "huge".

-verbose
    Makes the program talkative.  This is mainly useful for debugging,
    but since it displays all the font files it opens, successfully or
    not, it can be used to determine which files are needed.  The needed
    files can be created if they don't already exist.  They can also be
    put on your workstation's local disk to improve performance.

The rest of the options are rarely used:

-v <mi>, -h <mi>
    Set the vertical (horizonal) margin.  Next argument is the margin, in
    milli-inches.  Default is 1000 milli-inches each, which is the same
    default used by many common DVI printing programs.  If you find a lot
    of "off-screen glyph" errors, and you have the paper size set cor-
    rectly, try changing these parameters.  (Besides 1000, the second
    most common value expected is 0 for both margins.)

    Note that the default corresponds to the current TeX standard.  If
    you find you have to use some other value to make your output look
    right, some other piece of software you are running is obsolete.

-p <s> <e>
    Limits the display to pages <s> through <e> inclusive.  You can only
    specify one page range at a time, but you can specify multiple -p
    options, each specifying a page range.  When you specify page ranges,
    DVIDIS will only "see" pages within the ranges given.  Nothing you
    can do while the program is running will let you display any page
    not within any page range - DVIDIS will simply skip past the pages.

-f    Causes the program to look in "USER$RST" rather than "TEX$RST" for the
    fonts.  This command is meaningless for the PK version of DVIDIS, and
    of little use even in the RST version.

-d    Debug.  Generates a lot of output that's useful only to developers.

Program    Installation


DVIDIS consists of a single image, DVIDIS.EXE, that runs on an VAXStation
with VWS V3.0 or later.  It runs as a normal user-mode image, and needs no
special privileges.  DVIDIS uses a fair amount of memory as it runs, so be
sure to provide a reasonable working set - at least 1200 pages, 2000 or more
is better.  In order for DVIDIS to receive its arguments, it must be started
with a foreign command line, given by something like:

        $ DVIDIS :== $DEV:[DIR]DVIDIS

Two "environment variables" can be set to control DVIDIS, and you can specify
font substitutions.  The environment variables - typically, logicals, but
if no logicals are defined any DCL symbol of the same name will be used -
are:

DVIDIS_FILE_FORMAT
    A string that specifies how to construct a file specification for
    a font file, given a font name and a dots-per-inch value.  The
    font name will be substituted for %s; the dots-per-inch value for
    %d.  You must have EXACTLY one of each, in either order; you may
    NOT have any additional occurences of "%".

    There are two common schemes for storing PK font files:

        One directory, DEV:[DIR], font "name" at "ddd" dots
        per inch is file name.dddPK.  A format string for
        this case would look like "DEV:[DIR]%s.%dPK".

        One root directory, DEV:[DIR.]; fonts at "ddd" dots
        per inch are in subdirectory [.DPIddd], with font
        "name" in name.PK.  A format string for this case
        would look like "DEV:[DIR.DPI%d]%s.PK".

    If DVIDIS_FILE_FORMAT is not defined, the default format string
    is "TEX_FONTS:[DPI%d]%s.PK".  This corresponds to the second way
    of organizing the font files, and assumes that TEX_FONTS is a
    rooted logical translating to something like DEV:[DIR.].

    You can only specify a single file format, but that file format
    could involve a logical that translates to a search list.  For
    example, using the default file format, you might do:

        $ DEFINE TEX_FONTS $DISK1:[TEX.PK.],NODE::TEX_FONTS:

    where "NODE" is the name of a node with more fonts than you are
    willing to store locally.  On NODE, TEX_FONTS must be a SYSTEM
    logical name that translates to a rooted directory.  (If you
    have proxy access to NODE, you could define TEX_FONTS in your
    login file on NODE).  Because of a VMS bug, it isn't possible
    to use something like NODE::DEV:[DIR.] to avoid needing a logical
    name on NODE.  (This bug appears in VMS Version 4.5.  If you
    a more recent version, the bug may have been fixed.)

            I M P O R T A N T   N O T E

    The definition of DVIDIS_FILE_FORMAT will be used as a printf()
    format string.  The "d" and "s" format specifiers MUST be in
    lower case; if you make them upper case, the format will not
    work.  Note also that DCL forces characters to upper case unless
    they are inside a quoted string.  Hence, your definition should
    look something like:

        $ DEFINE DVIDIS_FILE_FORMAT "TEX_FONTS:%s.%dPK"

DVIDIS_FONT_SIZES
    This variable must translate to a list of all dot-per-inch values
    at which you have any fonts available.  The list consist of just
    the numbers (the "ddd" values discussed above), separated by
    commas.  DVIDIS will never find a font at a size not given in
    the list.

    The default list is:

        100,121,145,174,180,208,210,225,240,250,263,270,274,
        300,329,360,432,518,622,746,895,896,1074,1075,1289,
        1290,1547,1548

    which is the list of values I've got.  Extra values will slow
    DVIDIS down a bit when it has to open a file, but not by much,
    so you can use the default unless you have some sizes I don't.

    Note that this list is NOT a search list, use:

        $ DEFINE DVIDIS_FONT_SIZES "300,329,360"

    WITH THE QUOTATION MARKS.  If you leave the quotation marks off,
    DVIDIS will never use anything but the first value you list.

Font Substitution


If DVIDIS is unable to find a font as specified, it will check to see if you
have defined a substitute for it in any of three substitution files.  If you
are displaying file jobname.DVI, the files are:

         jobname.SUB        in the same directory as jobname.DVI;
        TEXFONTS.SUB        in the current directory;
        TEX$INPUTS:TEXFONTS.SUB

Every time a substitution is needed, the files present are checked, in the
order given, each from beginning to end, to try to find a substitute.  Only
the first match is used, however.

Each of the substitution files has the same format.  It's a simple ASCII file,
with one substitution per line.  Comments, as in TeX, are introduced by "%"
and continue to the end of the line.

A substitution line has either of two forms:

    oldname.oldsize -> subname.subsize
    oldname            -> subname

The first format substitutes only for a particular font name and size.  The
second format substitutes for a particular font name at any size.

Spaces can be used freely in substitution lines.

Since only the first match is used, and the files are always read from the
first line onward, you should specify particular substitutions - those with
a size - before generic ones.

It's not an error for the substituted font file not to be found - DVIDIS will
proceed to look for "nearby" fonts, possibly substituting for them as well.

The DVIDIS distribution includes a TEXFONTS.SUB file that substitutes CM fonts
for AM fonts.  This should allow you to display DVI files created using older
versions of TeX.

Getting the Find and Remove Keypad Keys to Work


The Find and Remove keypad keys use OSC functions to control the terminal
window.  OSC's must be enabled; from questions I've received, it seems that
many people are not enabling them.  To enable OSC's, issue the following
command from DCL (in a privileged account):

    $ DEFINE/SYSTEM/EXEC UIS$VT_ENABLE_OSC_STRINGS TRUE

Known Bugs and Restrictions


If the original TeX run specified a magnification value other than 1000, the
spacing will be incorrect.  The only current work-around is to re-run TeX
without the magnification.

Author:  Jerry Leichter, based on work of Bill Gropp's, which in turn was
based on a lot of earlier work by others; with additional input from Bert
Beander at DEC.  Comments/questions/suggestions to Jerry Leichter at

        [e-mail]
       or
        [e-mail]